Skip to main content
Version: 5.1.1.0

HTTP Caller

Description​

This channel allows to invoke any HTTP method. You may provide any Message content, Query parameters and HTTP-Headers. You also may parse response message content and error message content. Of course not all of this is sensible with all the HTTP methods. E.g. Query parameters are only usable with GET and POST calls and a request content is not allowed in GET calls.

Purpose of object​

Use this channel if the specialized channels like HTTP Post Sender or HTTP Sender (Parameter) are not appropriate. E.g. the HTTP Post Sender parses the error content only if the Status code is 500.

Since Orchestra Version​

Introduced in version 4.3.3.0

Configuration​

The dialog to configure the HTTP Caller is on the right-side panel and looks like this:

Step by Step​

  • Endpoint
    Here you may select Static endpoint or Dynamic endpoint.
    If Dynamic endpoint is selected, the channel uses a parameter ctrl_endpoint.
    The caller must provide the actual URL as the value of this parameter.
    In this case, the URL defined in the Service-URL is not used.
    If a proxy server is defined in the Service-URL, this proxy is used even if Dynamic endpoint is selected.

  • Service-URL
    Here, an Environment Entry of type Uniform Resource Locator is selected.
    It contains the URL to call if Static endpoint is selected.
    If a proxy server is defined in the Environment Entry, it is used even when Dynamic endpoint is selected.

  • Connect-Timeout
    Sets a specified timeout value to be used when opening the HTTP connection.
    If the timeout expires before the connection is established, an error is raised.
    A timeout of 0 is interpreted as an infinite timeout.

  • Read-Timeout
    Sets the read timeout.
    A non-zero value specifies the timeout when reading the HTTP response.
    If the timeout expires before data is available to read, an error is raised.
    A timeout of 0 is interpreted as an infinite timeout.

  • Security

    • Authentication
      Here you may select an authentication type. Options include:

      • No authorization required
      • Username/Password
      • Use preemptive authorization (Username/Password)
      • Use certificate authorization
      • Use OAuth2.0 authentication

      If you select Use certificate authorization, the chosen user credential must contain a PKCS#12 Key Pair.
      See Credentials for more information about user credentials and key pairs.
      Also refer to the best practice guide Web Service Security in SOAP web service calls for details on importing a Key Pair.

OAuth can be used for authentication. First, a Json Web Token (JWT) is requested from an identity provider and appended directly to the actual request.

To use this feature, you must make the following configurations.

Currently, two different grant types are supported. Additional request parameters cannot be added to OAuth authentication at this time.

  • Grant Type:

    • Password-Grant – is a way to exchange a user's credentials for an access token.

      The following information is required and added to the token request:
      Client-Identifier, Client-Secret, Username, Password, Identity Provider

      • The Identity Provider is a URL to a token endpoint.
      • The Client-Identifier and the Client-Secret are base64-encoded and added to the request header and body as authentication.
      • The Username and the Password are added to the body.
      • Currently, the same user credentials are used, which are also used for username/password authentication.

    • Client Credentials – is used when applications request an access token to access their own resources, not on behalf of a user.

      • Client Credentials (Header): sends Client-ID and Client-Secret in the Request Header.
      • Client Credentials (Body): sends Client-ID and Client-Secret in the Request Body.

      The following information is required and added to the token request:
      Client-Identifier, Client-Secret, Identity Provider

      • The Identity Provider is a URL to a token endpoint.
      • The Client-Identifier and the Client-Secret are base64-encoded and added to the request header or body.

  • User-Credentials:
    User with the same username and password as on the identity provider.
    User type has to be a Technical login.

  • Identity-Provider:
    A URL to a token endpoint of the identity provider (authorization server).

  • Client Credential:
    Used to select user credentials with Client-Identifier and Client-Secret that are relevant.

    • Client-Identifier: the identifier of the user at the identity provider.
      It is located at the Identity Provider and is set up in Credentials Username/Password as Account name.

    • Client-Secret: a secret generated by the identity provider.
      It is also located at the Identity Provider and is set up in Credentials Username/Password as Password.

  • Certificate Check:
    SSL settings for Identity Provider access.
    This can be used if the Identity Provider has an SSL connection and the certificate is a self-signed X.509 certificate.

    • For configuration, use the certificate authentication as a reference.

  • User-Credentials:
    A user credential of type Technical login.
    If you work with No authorization required, no selection is needed here.

The Certificate Check panel allows a user to configure client-side HTTPS connection details.

  • User-Credentials (type = Technical login):
    The public/private key pair in PKCS#12 format to be used for authorization.

  • Trusted Server (optional, type = Trusted server):
    Allows checking the server's public key certificate presented by the server when the client makes a request.

  • Trusted Signer (optional, type = Trusted server):
    Verifies whether the server's certificate is signed by the specified certificate and can therefore be trusted.

  • Check Certificate Chain (optional):
    Checks if the certificate chain is correctly signed (i.e., certificate n is signed by certificate n + 1).

  • Check Validity (optional):
    If enabled, checks whether the certificate is expired.

  • Check Signers Against Trust Store:
    If enabled, ensures that one certificate in the chain (typically the last one) is present in the trust store.

  • Cipher Suites (optional):
    Enforces specific cipher suites for use in TLS.
    The cipher suites should be entered as comma-separated values in the text box, e.g.:
    "TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA"

Detail settings​

In the tabulator panels under Detail settings you have to configure the parts of an HTTP communication.

Base settings​

In this panel the most basic settings of an HTTP call are to be configured.

  • Standard
    In this box, you must select an HTTP method. The following methods are selectable:
    GET, POST, PUT, HEAD, DELETE, OPTIONS, TRACE, and <user defined>.
    If <user defined> is selected, the Overwrite field is enabled, allowing you to enter a custom method name.

  • Ok-Status
    This field contains a comma-separated list of status codes representing success.
    If the HTTP response has status code 200 or any code listed here, the response is handled as defined in the Response tab.

  • HTTP-Header
    In this list, you can add additional HTTP header fields.
    If you add an entry with the name X, a channel parameter named HDR_X is generated.
    The value of this parameter is then used as the value of the HTTP header X in the HTTP request.

Query​

In this panel you may add query parameters for a GET or a POST call.

In this list you can add query parameters of the HTTP call. Typically, query parameters are used in GET and sometimes in POST or PUT calls.

If you add an entry in this list having a name X then a channel parameter named QRY_X is generated. The value of this parameter then is added as query parameter X=value to the URL of the HTTP request.

E.g. if you have a parameter invoice_nr and the static URL http://test.soffico.de/invoices the channel gets a parameter QRY_invoice_nr. If you assign the value 1234 to this parameter and call the channel, it will result in a new URL http://test.soffico.de/invoices?invoice_nr=1234 which is then transferred to the server.

Request​

In this panel you may define if and how a request content is sent in the HTTP call. Typically this is used together with a POST or a PUT call.

  • If the field Request is set to Enabled the channel gets an input parameter MSG of type Message.

  • Chunked mode: In case of large messages the transfer encoding chunked will reduce memory consumption because Orchestra need not serialized the message completely in the memory before sending it over the HTTP connection.

  • The value of the field Content-Type is written as HTTP header Content-Type.

  • The message is then serialized using the selected Serializer and the resulting byte stream is written as HTTP message content to the server. In most cases the XML writer is used.

Response​

In this panel you may define if a response content is received as part of the HTTP response and how it is parsed. Typically this is used together with a GET or a POST call.

If the field Response is set to Enabled the content of the HTTP response is parsed by the selected Deserializer. In most cases the XML reader is used expecting XML content. The resulting Message is then returned as value of the output variable MSG.

There are two parsing modes parse on creation (the default) and parse on demand.

  • parse on creation - the data are parsed by the selected deserializers while reading the byte stream. If in this process an error occurs, it is visible only in the log file because no process instance exists yet.

  • parse on demand - the byte stream is read binary without interpreting it; together with the data the configuration of the selected deserializer is stored. If the message is accessed, e.g. by a mapping, it is parsed using the attached deserializer configuration. If the deserializer throws an error it can be handled by from the process instance.

Error​

If an HTTP call returns an error it may send an error content, e.g. an HTML page describing the error. In this panel you may define if an error content is received and how it is parsed.

Error: From this box, you can select two modes: Generate exception on error and Return status code and optional error message.

  • If Generate exception on error is selected, the caller of the channel receives an error if a status code is received which is not a success code. Success codes are 200 and all codes contained in the Ok-Status field in the Base settings.

  • If Return status code and optional error message is selected and the status code is not a success code, the status code is returned as the value of the output variable HTTP_STATUS, and a short string describing the code (like "Not found") is returned as the value of the output variable HTTP_MESSAGE. If the status code is contained in the Err-Status field, the error content of the response is parsed with the configured deserializer. Typically, the error content contains an HTML page describing the error. Therefore, the Binary reader is most appropriate in this case.

  • Err-Status: Here, you may enter a comma-separated list of status codes. The error content is only parsed using the configured deserializer if this field contains the status code. The result of parsing the error content is a Message which is returned as the value of the output variable MSG.

Parameters​

Parameter nameDirectionDescription
ctrl_endpointIngoingThis parameter is visible if you selected Endpoint as a parameter. It is used to overwrite the target URL.
ctrl_credentialIngoingThis parameter is visible if you selected Use dynamic credentials. It is used to overwrite the used credential.
DYNAMIC_SERVICE_URLIngoingOptional parameter to overwrite the Service-URL environment entry. See EnvironmentEntryBuilder for details.
HTTP_STATUSOutgoingThe returned HTTP status code.
HTTP_MESSAGEOutgoingThe returned HTTP status message.
MSGOutgoingResponse message (the content if available).

See also​

For special cases of HTTP invocations use the channels HTTP Sender (Parameter) and HTTP Post Sender.

To accept HTTP invocations you can use the channels HTTP GET Receiver, HTTP POST Receiver (General) and HTTP POST Receiver (Parameter).

A more general approach to call a remote service using HTTP is the [REST Service Client]. It is also more flexible in creating and interpreting the message content.

You also can implement an HTTP server with the REST Service Provider.